home *** CD-ROM | disk | FTP | other *** search
/ Video Toaster 4.0 / Video Toaster v4.0.iso / programs / documentation / switcherarexx.doc < prev    next >
Text File  |  1993-12-13  |  22KB  |  491 lines
  1.     Video Toaster Switcher Arexx Manual   6/6/93
  2.  
  3.  
  4.     Note about ARexx:  The Video Toaster is compatible with the ARexx
  5. programming language.  However, due to the complex and technical nature of
  6. programming, users of ARexx cannot be supported by NewTek Technical
  7. Support.  Its inclusion is intended primarily for developers, programmers,
  8. and advanced users who are familiar and comfortable with programming
  9. concepts.  Commands are subject to change without prior notice.
  10.  
  11.     The Switcher Arexx interface has been implemented as a function host,
  12. rather than the more common command host interface (e.g.  ToasterPaint).
  13. Arexx function hosts are initialized using the addlib() function with the
  14. name of the host or library.  The name of the switcher host is
  15. 'ToasterARexx.port'  and it is case-sensitive.  ARexx messages sent to the
  16. Switcher must be in function call format.  This means that all commands
  17. must be given as arguments to the function Switcher(), rather than being
  18. sent as direct commands to an ARexx command host.  If the switcher command
  19. has any parameters, then they too must be given as arguments to Switcher()
  20. or the command will fail.  Furthermore, all parameters should be uppercase.
  21. Unless otherwise noted, all function commands return 0 if they were
  22. sucessfully executed, and 10 if a failure occurred.  ARexx messages will
  23. only be accepted and processed when the main Switcher control panel is
  24. active.  At other times, ARexx messages will be accepted and will remain in
  25. the Switcher's ARexx message port queue until the primary switcher control
  26. panel is active, at which point they will execute.
  27.  
  28.     Most of the commands that directly impact the Switcher will also show up on
  29. the Switcher interface.  Almost all ARexx commands that impact the Switcher
  30. behave exactly like their corresponding manual user interface functions
  31. from the Switcher interface.  In particular, they are restricted by the
  32. active controlling effect as to whether or not their requested function
  33. will be granted.  If an ARexx command function is aborted by a controlling
  34. effect, an OK return code may still be returned.  In the case of a failure
  35. code, the current Switcher settings remain unchanged.
  36.  
  37.     Note:  There is an additional Project (intended primarily for ARexx or
  38. kiosk use) that is shipped with the Video Toaster.  It is called
  39. Positionables,and can be found within the Projects directory.  It contains
  40. four grids (effects banks) of each Positioner effect.  If you wish to
  41. use this Project, rename the Project filename from Positionables to
  42. ###.PJ.Positionable (where ### is a three digit number, the switcher
  43. doesn't like project comments longer than 12 chars).  When the Toaster next
  44. accesses the Projects directory, it will list it as available.
  45.  
  46. Arexx Command Set:
  47.  
  48.     Switcher( AUTO )
  49. This command will invoke an AUTO transition.
  50.  
  51.     Switcher( UATO )
  52. This command performs an un-auto, the equivalent of a Shift-Spacebar action
  53. to reverse a partially transitioned effect back off screen.
  54.  
  55.     Switcher( TBAR, <TBar level> )
  56. This command will invoke a TBar jump movement to the specified level
  57. (0-511).  A failure code will be returned if the level argument is invalid.
  58.  
  59.     Switcher( TAKE )
  60. This command will invoke a TAKE.
  61.  
  62.     Switcher( SLOW )
  63.     Switcher( MEDM )
  64.     Switcher( FAST )
  65.     Switcher( SVAR )
  66. The above commands set the speed active for the transition that is
  67. currently in effect. SVAR sets the effect to the last duration chosen with
  68. the variable speed selector.
  69.  
  70.     Switcher( FREZ )
  71. This command toggles the current video state of the Switcher between live
  72. and frozen digital video.
  73.  
  74.     Switcher( NOPR )
  75. This command is a NOP.
  76.  
  77.     Switcher( FRES )
  78. This command resets the frame base count to the moment this command was
  79. processed.
  80.  
  81.     Switcher( WAIT, <Frame count> or GPI )
  82. This command can wait for either a specified frame count or for a GPI
  83. trigger.  If 'GPI'  is the specified argument, this function will wait for
  84. a GPI trigger to occur before continuing.  The trigger can be either a
  85. positive or negative trigger.  In the case of GPI triggering being
  86. disabled, this function will become a NOP.  If 'GPI'  is not the specified
  87. argument, then the argument is assumed to be a digit field specifying a
  88. frame count.  In this case the command will wait until the specified frame
  89. count from the last frame base count is reached.  In the case of specified
  90. frame count already exceeded, this function will return immediately.
  91.  
  92.     Switcher( CLIP, <Clip level> )
  93. This command will invoke a Clip jump movement to the specified level
  94. (0-257).  A failure code will be returned if the level argument is invalid.
  95.  
  96.     Switcher( KEYM )
  97. This command toggles the current key mode state of the Switcher.
  98.  
  99.     Switcher( M001 )
  100.     Switcher( M002 )
  101.     Switcher( M003 )
  102.     Switcher( M004 )
  103.     Switcher( MDV1 )
  104.     Switcher( MDV2 )
  105.     Switcher( MBKG )
  106. The above commands select the specified video source for the Main output.
  107.  
  108.     Switcher( P001 )
  109.     Switcher( P002 )
  110.     Switcher( P003 )
  111.     Switcher( P004 )
  112.     Switcher( PDV1 )
  113.     Switcher( PDV2 )
  114.     Switcher( PBKG )
  115. The above commands select the specified video source for the Preview
  116. output.
  117.  
  118.     Switcher( O001 )
  119.     Switcher( O002 )
  120.     Switcher( O003 )
  121.     Switcher( O004 )
  122.     Switcher( ODV1 )
  123.     Switcher( ODV2 )
  124.     Switcher( OBKG )
  125. The above commands select the specified video source for the Overlay
  126. output.
  127.  
  128.     Switcher(CHGR,<Grid Letter>)
  129. This command is the same as clicking on one of the lettered Grid buttons.
  130. It will accept a letter from A-I and switch to that grid.
  131.  
  132.     Switcher( GRID, <ToolBox Effect> )
  133. This command selects the specified ToolBox Effect as the currently active
  134. Effect in the Switcher.  The ToolBox Effect address is a 3 character code.
  135. The first character is the grid selector code A-I for the ToolBox grids.
  136. The second character is the grid row selector 1-4, and the the
  137. third character is the column selector 1-8.  This function will return a
  138. failure code if the specified ToolBox Effect does not exist.
  139.  
  140.     Switcher(DOEN)
  141. This command is the same as pressing the enter key on the numeric keypad.
  142. When you are selecting CG pages, it will load the currently displayed CG
  143. page, if you are selecting effects, it will load that effect.  If you are
  144. selecting framestores it will load or save them.
  145.  
  146.     Switcher(GOCG)
  147.     Switcher(GOLD)
  148.     Switcher(GOSA)
  149. These commands are now obsolete.  They have been left in for compatibility
  150. reasons, but they do nothing.
  151.  
  152.     Switcher(KEYP)
  153.     Switcher(KEYN)
  154. These commands are equivalent to hitting the '+'  or '-'  keys on the
  155. numeric keypad, which cycle through framestore names, or CG pages,
  156.  
  157.     Switcher(STAT,<Command>)
  158. This command returns information about the status of the Switcher.  The
  159. return value depends on which command is used.  The possible commands are:
  160.  
  161.         MAIN    Return status of the Program (main) row.  The binary representation
  162.             of the number returned will have a bit set for which input is
  163.             selected on the Program row.  Thus if input 1 is selected, the
  164.             number returned will be 1 (binary 00000001).  Similarly, input 3
  165.             would yield 8 (binary 00000100), DV2 would yield 64 (binary 00100000),
  166.             as it is the sixth button on the row, and fills only the sixth bit
  167.             (from the right) in the binary rep. of the returned value.
  168.  
  169.         PREV        Return status of the Preview row in the same format as MAIN
  170.  
  171.         OVLY        Return status of the Overlay row in the same format as MAIN
  172.  
  173.         FREZ        Return status of the Freeze button: 0 for live video, ~0 for frozen video
  174.  
  175.         TEXT        Return contents of popup menu in quick access panel
  176.  
  177.         TBAR        Return T-Bar position (0-511)
  178.  
  179.         KEYM        Return Key Mode ('BLACK', 'WHITE', or 'OFF')
  180.  
  181.         CLIP        Return clip level (0-257, 0 and 257 are off)
  182.  
  183.         SPED        Return current speed setting.  The number returned is a 16-bit value
  184.             whose lowest 2 bits indicate which preset speed is in effect (M=00,
  185.             F=01, V=10, and S=11).  The remaining 14 bits will hold the variable
  186.             speed.  If the 16 bit value is all 1s or 0s (i.e. -1 or 0), it means
  187.             variable speeds won't work with that particular effect.
  188.  
  189.         FCNT        Return frame count for current effect (0-9999 frames)
  190.  
  191.         KNUM        Return number in quick access panel
  192.  
  193.         FXNM        Return the effect name for the current effect
  194.  
  195.         GRID    Current effect number counting from 1 at effect A11 (-1 for CG or anim)
  196.  
  197.         BANK    Current effects bank counting from 0 for bank A
  198.  
  199.         INFO    Current numeric keypad selection (SA, LD, CG).
  200.  
  201.         BACK    Current Background color
  202.  
  203.         BORD    Current Border color
  204.  
  205.         TERM    Current termination settings returned as a number whose lowest
  206.             4 bits represent the state of the four input terminators (input 4
  207.             is least significant bit, input1 most significant bit).
  208.  
  209.         SGPI    Current GPI mode (POS,NEG,OFF)
  210.  
  211.         FACE    Number of monitors (2 or 3)
  212.  
  213.         FMDV    List of available framestore devices separated by commas
  214.  
  215.         PJDV    List of available project devices separated by commas
  216.  
  217.  
  218.     Switcher(FMSV, <Framestore number>, <Comment>,0)    1-field save
  219.     Switcher(FMSV, <Framestore number>, <Comment>,5)      4 field save
  220.     Switcher(FMSV, <Framestore number>, <Comment>)        4 field save
  221. This command saves the contents of the frame buffer selected on the
  222. preview bus to the current framestore device with the specified number
  223. and comment. If a frame with that number already exists, the command
  224. will fail.  If the last argument is 0, only 1 field of video will be saved,
  225. if that argument is 5, or is absent a standard 4-field save will occur.
  226.  
  227.     Switcher( PAGE, <Page number> )
  228. This command activates the specified CG page (0-99).  This function will
  229. return a failure code if the CG is not active or the specified page is
  230. empty.
  231.  
  232.     Switcher( FMLD, <FrameStore number> )
  233. This command loads the specified FrameStore (0-999) from the active
  234. FrameStore device.  This function will return a failure code if the
  235. specified FrameStore is not found.
  236.  
  237.     Switcher( BKLD, <Project number> )
  238. This command loads the book from the specified Project of the active
  239. Project device.  This function will return a failure code if the CG is not
  240. active or the specified book does not exists.
  241.  
  242.     Switcher( PJLD, <Project number> )
  243. This command loads the specified Project of the active Project device.
  244. This function will return a failure code if the specified Project is not
  245. found.  Note that this function DOES NOT update the CurrentProject file to
  246. denote the newly loaded Project as the active Project.
  247.  
  248.     Switcher( PJDV, <Project device string> )
  249.     Switcher( FSDV, <FrameStore device string> )
  250. The above command designates a new Project or FrameStore device
  251. respectively.  The device string must be a physical device name, not a
  252. logical or volume name.  This function will return a failure code if the
  253. specified device could not be found or was found without a Project or
  254. FrameStore directory respectively.
  255.  
  256.     Switcher( TOWB )
  257. This command will pop the WorkBench screen up to the front and disables the
  258. Switcher/Toaster system.  This function will return a failure code if
  259. WorkBench could not be opened.
  260.  
  261.     Switcher( TOSW )
  262. This command will pop the Switcher screen up to the front and enable the
  263. Switcher/Toaster system.
  264.  
  265.     Switcher( QUIT )
  266. This command will completely shut down the Switcher/Toaster system upon its
  267. arrival.  All Switcher/Toaster resources will be freed and the program
  268. exited.
  269.  
  270.     Switcher( BACK , <Index # or -1> [, <Custom BG color>] )
  271. This command will select the specified matte (background) color either from
  272. indexing the current config slice matte color FGs (0-8) or a specified
  273. custom matte color if the index is specified as -1.  Custom color
  274. specifications have a valid range of 0-4096.  If you want to directly
  275. specify snow, specify your custom color as a negative 16 bit word value.
  276.  
  277.     Switcher( BORD , <index #> )
  278. This command will select the specified border color via the index specified
  279. for the current config slice border color FGs (0-7).
  280.  
  281.     Switcher( KOFF )
  282.     Switcher( KBLK )
  283.     Switcher( KWHT )
  284. The above commands forces the Key mode to be off, on with black enabled,
  285. and on with white enabled respectively.  Issuing this command does not
  286. guarantee that the key mode will be forced to the desired mode.  If it
  287. doesn't work, the function will return a failure code.
  288.  
  289.     Switcher( LVID )
  290.     Switcher( FVID )
  291. The above commands forces the Video mode to be live or frozen respectively.
  292. Issuing this command does not guarantee that the video mode will be forced
  293. to the desired mode.  If it doesn't work, the function will return a
  294. failure code.
  295.  
  296.     Switcher( NOMO )
  297. The above command does a frame capture along with motion removal.
  298.  
  299.     Switcher( PJSV, <Project number>, <Comment> )
  300.     Switcher( FMSV, <FrameStore number>, <Comment> )
  301. The above commands save the specified Project or FrameStore respectively.
  302. In the case of project saving, the CurrentProject file IS NOT updated to
  303. reflect the saving of the specified project.
  304.  
  305.     Switcher( PJDL, <Project number> )
  306.     Switcher( FMDL, <FrameStore number> )
  307. The above commands delete the specified Project or FrameStore respectively.
  308. These functions will fail if something goes wrong.  In the case of project
  309. deleting, the CurrentProject file IS NOT removed to reflect the deleting of
  310. the specified project when it is also the currently active project.
  311.  
  312.     Switcher( PJRN, <Project number>, <Comment> )
  313.     Switcher( FMRN, <FrameStore number>, <Comment> )
  314. The above commands rename the specified Project or FrameStore respectively.
  315.  
  316.     Switcher( SGPI, <OFF|POS|NEG> )
  317. The above command sets up the Switcher GPI trigger system.  'OFF'  disables
  318. the system, 'POS'  enables the system for positive GPI triggers, and 'NEG'
  319. enables the system for negative GPI triggers.  The changes to the Switcher
  320. GPI trigger system made by this function WILL NOT be reflected in the
  321. HardSets file.  Tech note:  GPI input occurs on pin 6 of the second
  322. gameport (bit 7 of CIAA port A).
  323.  
  324.     Switcher( DISW )
  325.     Switcher( ENSW )
  326. The above commands are for disabling/enabling return of control from the
  327. ARexx environment back to the Switcher.  The primary use of these commands
  328. is in running the Switcher entirely from ARexx scripts without allowing
  329. input from the Switcher interface (keyboard, mouse, etc.) to interfere with
  330. the execution of the ARexx script.  Only diskchanges will still be
  331. processed.
  332.  
  333.     Switcher( DIIM )
  334.     Switcher( ENIM )
  335. The above commands are for disabling/enabling rendering, the SoftSprite
  336. system, and the mouse and keyboard IDCMP.  These calls can be used to speed
  337. up the processing of ARexx switcher commands at the expense of visual
  338. feedback of the transition.  When enabled, the Switcher display will be
  339. completely redrawn.
  340.  
  341.     Switcher( MEMC [, 'L' ] )
  342. The above command returns the amount of free CHIP memory or the largest
  343. CHIP chunk if the 'L'  option is used.  This command is ARexx dependent.
  344.  
  345.     Switcher( MEMF [, 'L' ] )
  346. The above command returns the amount of free FAST only memory or the
  347. largest FAST only chunk if the 'L'  option is used.  This command is ARexx
  348. dependent.
  349.  
  350.     Switcher( CKTP )
  351.     Switcher( CKCG )
  352.     Switcher( CKLW )
  353. The above commands check for the existence of ToasterPaint, CG, and
  354. LightWave respectively.  They return a 1 if the program entity is currently
  355. loaded and 0 if not.  These commands are ARexx dependent.
  356.  
  357.     Switcher( LDTP )
  358.     Switcher( LDCG )
  359.     Switcher( LDLW )
  360. The above commands attempt to load ToasterPaint, CG, or LightWave
  361. respectively if those program entities are not already loaded.  These
  362. commands can be dangerous if the load fails and a requester comes up,
  363. hanging ARexx.
  364.  
  365.     Switcher( DPTP )
  366.     Switcher( DPCG )
  367.     Switcher( DPLW )
  368. The above commands will unload ToasterPaint, CG, or LightWave respectively
  369. if those program entities are loaded.
  370.  
  371.     Switcher( STTP )
  372. This command will enter ToasterPaint if and only if it is currently active,
  373. otherwise this command is a NOP.  Once entering ToasterPaint, your ARexx
  374. message will not be returned until ToasterPaint exits back to the Switcher.
  375. So be careful that you don't hang yourself.
  376.  
  377.     Switcher( PJXI, <Project number> )
  378.     Switcher( FMXI, <FrameStore number> )
  379. The above commands test the existence of the specified Project or
  380. FrameStore respectively, returning a 1 if the entity exists, 0 if not.
  381. These commands are ARexx dependent.
  382.  
  383.     Switcher( PJNM )
  384.     Switcher( FSNM )
  385. The above commands return the current device name string of the Project and
  386. FrameStore systems respectively.  These commands are ARexx dependent.
  387.  
  388.     Switcher( PJCK, <Project device string> )
  389.     Switcher( FSCK, <FrameStore device string> )
  390. The above commands check for the existence of a Project or FrameStore
  391. directory on the specified Project or FrameStore device respectively.
  392. Returns a 1 if the directory exists, 0 if not , or -1 if the specified
  393. device is invalid.  These commands are ARexx dependent.
  394.  
  395.     Switcher( PJMK, <Project device string> )
  396.     Switcher( FSMK, <FrameStore device string> )
  397. The above commands attempt to make a Project or FrameStore directory on the
  398. specified Project or FrameStore device.  They return a 1 if the directory
  399. was created or already existed, 0 if something went wrong.  These commands
  400. are ARexx dependent.
  401.  
  402.     Switcher( PJBD )
  403.     Switcher( FSBD )
  404. The above commands force the Switcher internal string tables for the
  405. Project or FrameStore respectively to be rebuilt and updated.  The above
  406. commands are useful when you happen to dabble directly in the active
  407. Project or FrameStore directory.  The changes you might make will most
  408. likely be missed by the Switcher.  These commands insure that the Switcher
  409. (and other hosted entities) will know of these changes.
  410.  
  411.     Switcher( FSCT, <FrameStore device string> )
  412. The above command returns the number of FrameStores the specified
  413. FrameStore device can hold.  Returns a -1 if something went wrong with
  414. device access.  This command is ARexx dependent.
  415.  
  416.     Switcher( OGPI )
  417. This command causes an output GPI trigger to occur in accordance to the
  418. current settings of the GPI system.  This command is a NOP if GPI
  419. triggering is disabled.  Tech note:  GPI output occurs on pin 9 of the
  420. second gameport (potentiometer circuit).
  421.  
  422.     Switcher( CKGD, <ToolBox Effect> )
  423. This command checks the specified ToolBox Effect to see if it exists.  The
  424. ToolBox Effect address is a 3 character code.  The first character is the
  425. grid selector code A-I for the ToolBox grids.  The second character is
  426. the grid row selector 1-4, and the the third character is the column
  427. selector 1-8.  This function will return a failure on a bogus ToolBox
  428. Effect address.  Returns a 1 if the specified ToolBox Effect exists, 0
  429. otherwise.  This command is ARexx dependent.
  430.  
  431.     Switcher( RDGD, <ToolBox Effect>, <S | M | F | V> )
  432. This command reads the FieldCount of a ToolBox Effect's specified speed
  433. mode.  The ToolBox Effect address is a 3 character code.  The first
  434. character is the grid selector code A-I for the ToolBox grids.  The
  435. second character is the grid row selector 1-4, and the the third character
  436. is the column selector 1-8.  The speed mode must be specified as S (SLOW),
  437. M (MEDIUM), F (FAST), or V (VAR).  The above arguments must be specified correctly
  438. and the specified ToolBox Effect exist or this function will return a
  439. failure.  If all goes well, a FieldCount value will be returned.  This
  440. command is ARexx dependent.
  441.  
  442.     Switcher( WTGD, <ToolBox Effect>, <S | M | F | V>, <FieldCount> )
  443. This command writes the specified FieldCount to the specified ToolBox
  444. Effect's specified speed mode.  The ToolBox Effect address is as mentioned
  445. in the above command.  The speed mode must be specified as S (SLOW), M
  446. (MEDIUM), F (FAST), V (VARIABLE).  The FieldCount should be a value in the
  447. interval of 1-65535.  The above arguments must be specified correctly and
  448. the specified ToolBox Effect exist or this function will return a failure.
  449. If all goes well, the FieldCount value will be placed and ready for use.
  450.  
  451. Changing the FieldCount of a ToolBox Effect which is currently active may not
  452. always work, since the speeds are loaded when the effect is selected.  To be
  453. certain that the changes take effect, select a different effect, change the
  454. speed of the original effect, then reselect it.
  455.  
  456.     Switcher( TERM, <mask> )
  457. This command sets the termination for the four video inputs.  The mask will
  458. be a number from 0 to 15 whose bits (0-3) control the termination setting for
  459. inputs 1-4.
  460.  
  461.     Switcher( SRGB, <filename>,<field>,<bank>)
  462. This command saves the contents of one of the digital video buffer to a
  463. standard IFF24 type rgb file. The filename should include the complete file
  464. path. The bank argument should be 0 for DV1 and 1 for DV2. Field selects
  465. which of the 4 fields (0-3) of video stored in the frame buffer should be
  466. saved. Setting field to 4 will initiate motion removal and save 2 fields.
  467. Setting field to 5 will save a full 4-field 'color frame'. This is the best
  468. quality save.
  469. NOTE: Not all of these settings are currently implemented .
  470.  
  471.     Switcher(LRGB,<filename>,<bank>)
  472. This command loads an RGB image into the specified digital video buffer.
  473. The filename should include the complete file path.  The bank argument
  474. should be 0 for DV1 and 1 for DV2.
  475.  
  476.     Switcher(FACE,<monitors>)
  477. This command sets the interface to 2 monitor or 3 monitor mode, when
  478. monitor is 2 or 3 respectively.
  479.  
  480.     Switcher(GROF)
  481. This command turns off the image hilighting system and software
  482. mouse pointer.  Each call to this function MUST be matched with
  483. exactly one (1) call to the GRON function.  After this call no
  484. interface elements will be hilighted. The function returns a pointer to
  485. the bitmap structure used by the screen.
  486.  
  487.     Switcher(GRON)
  488. This command turns on the image hilighting system and software mouse
  489. pointer after a GROF.  Each call to this function MUST be matched with
  490. exactly one (1) prior call to the GROF function.
  491.